Skip to content

fix: FTS/Vector index race condition (GitHub Issue #64)#65

Merged
tryweb merged 1 commit intomainfrom
fix/fts-index-race-condition-64
Apr 5, 2026
Merged

fix: FTS/Vector index race condition (GitHub Issue #64)#65
tryweb merged 1 commit intomainfrom
fix/fts-index-race-condition-64

Conversation

@tryweb
Copy link
Copy Markdown
Owner

@tryweb tryweb commented Apr 5, 2026

Summary

  • Fix: FTS/Vector index creation fails with transaction conflict when multiple OpenCode processes start simultaneously (Issue FTS Index creation fails with transaction conflict (version 3010) #64)
  • Root cause: TOCTOU (Time-Of-Check-Time-Of-Use) race condition in ensureIndexes() - two processes both see no index, both try to create, loser gets Retryable commit conflict error

Changes

  1. Add isCommitConflict() helper - Detects LanceDB retryable commit conflict errors ("Retryable commit conflict" or "preempted by concurrent transaction")
  2. Re-verify after conflict - In catch block, call listIndices() and adopt index as success if another process created it
  3. Add jitter to backoff - baseDelay * 2^attempt + Math.random() * baseDelay to prevent thundering-herd re-collision
  4. Final-pass check - After all retries exhausted, call listIndices() one final time before declaring failure
  5. Unit tests - 6 tests covering all new behaviors (test/unit/index-race-condition.test.ts)

Testing

  • Docker verification: npm run verify - 34 tests pass ✓
  • All new unit tests pass ✓
  • TypeScript: 0 errors ✓

Spec Sync

  • Delta specs synced to main spec: openspec/specs/index-retry/spec.md - 3 new requirements, 7 new scenarios

Docs Updated

  • docs/backlog.md - Added BL-051
  • docs/roadmap.md - Added BL-051 to P1 list

- Add isCommitConflict() helper to detect LanceDB retryable commit conflict errors
- In catch block, re-verify index existence after commit-conflict before counting failure
- Add jitter to retry backoff to prevent thundering-herd re-collision
- Add final-pass existence check after all retries exhausted
- Add unit tests for all new behaviors
- Sync delta specs to main spec (openspec/specs/index-retry/spec.md)
- Update backlog.md (BL-051) and roadmap.md

Fixes: FTS index creation fails with transaction conflict when multiple OpenCode processes start simultaneously
@tryweb tryweb merged commit ce7b974 into main Apr 5, 2026
9 checks passed
@tryweb tryweb deleted the fix/fts-index-race-condition-64 branch April 5, 2026 06:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant